home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 076-100 / disk_095 / journal / journal.doc < prev    next >
Text File  |  1992-05-06  |  17KB  |  344 lines
  1. OVERVIEW:
  2.  
  3. JOURNAL is a program that records a sequence of mouse and keyboard events as 
  4. they occur and stores them in a file.  The file can be played back via the
  5. program PLAYBACK, thus causing the same sequence of events to occur again. 
  6. This is useful for creating demonstrations of programs (much like the "Guided
  7. Tours" on the Macintosh computer).  It also is useful for documenting
  8. repeatable bugs:  rather than trying to describe to CATS (or some third-party
  9. vender) what you did that revealed the bug, you could record the actions with
  10. JOURNAL, and send them the output file instead.  Finally, you can use JOURNAL
  11. to set up turnkey demo-disks for conferences and computer shows that will run
  12. unattended while you talk to customers.  It's even possible for PLAYBACK to
  13. restart itself when it comes to the end of the file.  In a future version,
  14. there will be a journal editor that allows you to add "special effects" like
  15. explanation windows that tell the viewer what you are doing, or that call up
  16. the narrator device to "speak" some information as your demonstration
  17. progresses. 
  18.  
  19. JOURNAL may not work with some programs the "take over" the system or bypass
  20. the Input.Device (see USAGE NOTES for additional information).
  21.  
  22.  
  23. HOW TO USE JOURNAL:
  24.  
  25. To run JOURNAL, type:
  26.  
  27.     1> RUN JOURNAL TO <file>
  28.  
  29. where <file> is the name of the journal file that you wish to produce.  JOURNAL
  30. should respond by displaying its version number and telling you how to cancel
  31. it, and by moving the pointer to the upper, left-hand corner of the screen. 
  32. Once the pointer has been moved, JOURNAL will record all the key presses and
  33. mouse movements that you perform, by writing them to the file that you
  34. specified.
  35.  
  36. This file will be used A LOT, so if it is on floppy-disk, be sure that the
  37. disk can be left in the drive, and that it has enough space available for
  38. the journal file.  The journal grows FAST, so do some exparimenting before
  39. you create a long journal file.  RAM: is a good place to write small journals,
  40. but may not be appropriate for long ones, as you may need your RAM space for
  41. the programs that you are running.
  42.  
  43. When you are done creating your journal, press CTRL-LEFTAMIGA-E.  This signals
  44. JOURNAL to stop recording events.  Once you get the "Joural Complete" message,
  45. any further actions will not be added to the journal file.
  46.  
  47.  
  48. HOW JOURNAL WORKS:
  49.  
  50. JOURNAL installs an input handler into the handler chain of the Input.Device. 
  51. This handler's priority puts it ahead of Intuition, so it sees the "undigested"
  52. events as they arrive from the Keyboard.Device, Gameport.Device, and
  53. Timer.Device.  When keyboard or mouse events are passed to the handler, it
  54. copies them into a linked list of events and signals JOURNAL that new events
  55. are ready, then passes the unmodified event list on to Intuition.  JOURNAL
  56. picks up the list of events and packs them into "TinyEvents" that take up
  57. fewer bytes, and records these in the output file.  To save even more space in
  58. the file, JOURNAL compresses multiple mouse move events into single output file
  59. records when possible, but records the number of events that were compressed,
  60. so that they can be recreated by PLAYBACK, if desired.  The amount of 
  61. compression is controlled by command-line options (see below).
  62.  
  63. When the handler sees that CTRL-AMIGA-E has been pressed, it signals JOURNAL,
  64. which tells the Input.Device to remove the handler from the chain and closes
  65. the journal file.
  66.  
  67.  
  68. JOURNAL OPTIONS:
  69.  
  70. JOURNAL supports a number of command-line options that modify its behavior:
  71.  
  72.     TO <file>       Designates <file> as the JOURNAL output file (the keyword
  73.                     "TO" is optional).
  74.     
  75.     DX x            Specifies the amount of x movement that can be compressed
  76.                     into one output event (mouse movements are added together
  77.                     until their conbined x-offsets exceed DX or their
  78.                     combined y-offsets exceed DY).  The default value is 8.
  79.  
  80.     DY y            Specifies the amount of y movement that can be compressed
  81.                     into one output event (mouse movements are added together
  82.                     until their conbined x-offsets exceed DX or their
  83.                     combined y-offsets exceed DY).  The default value is 8.
  84.  
  85.     SMOOTHX x       Specifies an alternate value for DX that is used when extra
  86.                     precision is needed (for example, when you need to draw
  87.                     a free-form line in a paint program).  This value is in
  88.                     effect when the SMOOTH and TRIGGER mask conditions are
  89.                     met (see below).  The default value is 1.
  90.  
  91.     SMOOTHY y       Specifies an alternate value for DY that is used when extra
  92.                     precision is needed (for example, when you need to draw
  93.                     a free-form line in a paint program).  This value is in
  94.                     effect when the SMOOTH and TRIGGER mask conditions are
  95.                     met (see below).  The default value is 1.
  96.  
  97.     SMOOTH mask     Indicates which qualifier keys MUST be pressed in order to 
  98.                     activate the SMOOTHX and SMOOTHY values.  Whan ALL the
  99.                     keys specified by the SMOOTH mask are pressed, and AT LEAST
  100.                     ONE of the keys designated by the TRIGGER mask is pressed,
  101.                     then the SMOOTHX and SMOOTHY values are used in place of 
  102.                     DX and DY.  By default, the left Amiga key specifies
  103.                     smoothing.
  104.  
  105.     TRIGGER mask    Indicates which qualifier keys trigger the use of SMOOTHX
  106.                     and SMOOTHY.  When ANY ONE of the keys indicated by TRIGGER
  107.                     mask is pressed, and ALL of the keys specified by the
  108.                     SMOOTH mask are pressed, then SMOOTHX and SMOOTHY are used
  109.                     in place of DX and DY.  By default, any qualifier key 
  110.                     triggers smoothing.
  111.  
  112. For people who understand "C" syntax, the expression that determines whether
  113. to use DX and DY or SMOOTHX and SMOOTHY is the following:
  114.  
  115.   if (((Qualifiers & SmoothMask) == SmoothMask) && (Qualifiers & TriggerMask))
  116.     use SMOOTHX and SMOOTHY
  117.    else
  118.     use DX and DY
  119.  
  120. Note that this provides considerable flexibility in specifying what will
  121. activate smoothing.  For example, to specify that pressing either button will
  122. cause smoothing, use:
  123.  
  124.     1> JOURNAL TO <file> SMOOTH 0 TRIGGER 0x6000
  125.  
  126. To specify that left Amiga plus left shift together with either button 
  127. should cause smoothing, use:
  128.  
  129.     1> JOURNAL TO <file> SMOOTH 0x0041 TRIGGER 0x6000
  130.  
  131. The complete set of qualifier values is listed in the include file 
  132. "DEVICES/INPUTEVENT.H".  Important values are listed here:
  133.  
  134.     Left Shift          0x0001
  135.     Right Shift         0x0002
  136.     Caps Lock           0x0004
  137.     Control             0x0008
  138.     Left ALT            0x0010
  139.     Right ALT           0x0020
  140.     Left Amiga          0x0040
  141.     Right Amiga         0x0080
  142.     Left Button         0x2000    
  143.     Right Button        0x4000
  144.  
  145. To determine the mask value, take the bitwise OR of the values for the
  146. qualifiers you want to use.   Note that the SMOOTH and TRIGGER masks should be
  147. specified in HEX, not decimal.
  148.  
  149.  
  150. HOW TO USE PLAYABCK:
  151.  
  152. To use playback, type:
  153.  
  154.     1> RUN PLAYBACK FROM <file>
  155.  
  156. where <file> is the name of a journal file recorded with the JOURNAL command.
  157. PLAYBACK should print a message telling you its version number and how to
  158. abort the playback, and then should begin playing back the recorded events. 
  159. All you have to do is sit back and watch. 
  160.  
  161. When PLAYBACK is running, you will not be able to control the mouse yourself,
  162. and the keyboard will have no effect (except for CTRL-C, which cancels 
  163. PLAYBACK).  This is so that you do not disturb the sequence of the journal
  164. being played back.
  165.  
  166. When the last event is played back, PLAYBACK will inform you that it is done.
  167.  
  168. To cancel PLAYBACK at any time, press CTRL-C.  This is the only key that has
  169. any effect while PLAYBACK is running.
  170.  
  171.  
  172. HOW PLAYBACK WORKS:
  173.  
  174. PLAYBACK installs an input handler into the handler chain of the Input.Device.
  175. This handler's priority puts it ahead of Intuition, so it can insert new
  176. events into or remove events from the stream seen by Intuition.  PLAYBACK
  177. reads packed events from the journal file and unpacks them into an event
  178. buffer where the input handler adds them to the event stream.  Since multiple
  179. mouse movements are compressed into single journal records, PLAYBACK must
  180. uncompress these by extrapolating intermediate mouse positions.  The input
  181. handler removes all keyboard and mouse events sent to it by the Input.Device
  182. so that these do not interfere with the journal being played back.  If the
  183. handler sees a CTRL-C it signals PLAYBACK that the user wants to abort the
  184. playback before it is complete.  PLAYBACK then requests the input.Device to
  185. remove the handler.
  186.  
  187. PLAYBACK uses a FIFO event queue to supply events to the input handler.  Since
  188. the handler may have to wait for some time to pass before it posts the next
  189. event in the queue, this allows PLAYBACK to "read ahead" in the journal file, 
  190. and prepare additional events for posting.  This makes the mouse movements
  191. smooth and un-interrupted.  When PLAYBACK fills the queue, it waits for the
  192. handler to post some events (freeing space in the queue).  You can control 
  193. the size of the queue via the EVENTS command-line option.
  194.  
  195.  
  196. PLAYBACK OPTIONS:
  197.  
  198. PLAYBACK supports a number of command-line options that modify its behavior:
  199.  
  200.     FROM <file>     Specifies the journal file to be played back (the keyword
  201.                     "FROM" is optional).
  202.  
  203.     EVENTS n        Specifies the size (in events) of the events buffer
  204.                     used to pass events from PLAYBACK to the input handler.
  205.                     EVENTS must be at least two.  The default value is 50,
  206.                     but it can be set as low as 10 and still provide acceptable
  207.                     performance for some tasks.  The number of events may need
  208.                     to be increased if you have many other tasks running, or
  209.                     are accessing the disk containing the journal file
  210.                     frequently, or have specified small DX and DY values when
  211.                     you recorded the journal file.
  212.  
  213.     SMOOTH          Specifies that compressed mouse moves should be expanded
  214.                     into multiple mouse moves of smaller offsets.  This makes
  215.                     the playback look smoother, and makes precise mouse moves
  216.                     possible without taking up space in the journal file.
  217.                     The default is SMOOTH.
  218.  
  219.     NOSMOOTH        Specifies that compressed mouse moves should be left
  220.                     compressed (i.e., no extrapolated events should be posted).
  221.                     This may be necessary if you need extremely quick response
  222.                     time or if you have specified a small DX and DY during
  223.                     recording and do not need to uncompress mouse moves.
  224.                     The default is SMOOTH.
  225.  
  226.  
  227. HOW TO COMPILE AND LINK JOURNAL AND PLAYBACK:
  228.  
  229. JOURNAL AND PLAYBACK were developed using the Lattice C compiler version 3.10. 
  230. I have tried to make it as generic as possible, but since I don't have the 
  231. Aztex C compiler, I don't know whether it works with Manx.  For Lattice C, all 
  232. you have to do is:
  233.  
  234.     1> lc -v journal playback
  235.     1> asm handlerstub
  236.     1> blink with journal.lnk
  237.     1> blink with playback.lnk
  238.  
  239. The '-v' option is so that no stack checking code will be produced.  Since the
  240. input handler runs on the Input.Device's stack, this would confuse the stack
  241. check code and probably crash the system (I never tried it, though).
  242.  
  243.  
  244. USAGE NOTES:
  245.  
  246. Since PLAYBACK plays back exactly what was recorded by JOURNAL, it is
  247. important that the initial conditions be the same for both JOURNAL and
  248. PLAYBACK.  If even one window is not where it was when your ran JOURNAL, then
  249. PLAYBACK may become hopelessly out of synchronization.
  250.  
  251. It is best to run JOURNAL from a freshly booted system, or a newly opened
  252. NewCLI or AmigaDOS window.   If the journal needs programs or other windows to
  253. be open, don't open them first and then run JOURNAL.  Instead, run JOURNAL and
  254. then open the windows or run the programs.  This way you can be sure that
  255. what you want will be there, and in the proper places.  If you are recording
  256. actions on the Workbench, you should start with all the disk windows closed,
  257. and the disks in their default positions then open them within the journal. 
  258. Beware that disk positions may change depending on the order in which they
  259. were inserted.
  260.  
  261. One "feature" of JOURNAL and PLAYBACK is that they do not know about disk
  262. insert requesters.  If a disk requester comes up, JOURNAL keeps right on
  263. recording mouse moves and key strokes.  If you cancel the requester, so will
  264. PLAYBACK.  But if you put in a disk and the requester goes away, there is no
  265. guarantee that the user who is playing back your journal will replace the disk
  266. in the same amount of time you did (in fact, he may never replace it), so the
  267. rest of the journal may become out-of-synch.  Worse yet, the user can pop a
  268. disk out of the drive at any time, which may cause a disk requester to come up
  269. that did not appear when you recorded the journal, or the user might have
  270. fewer disk drives than you do, so he may have to swap drives differently from
  271. how  you did.   All of these cases cause trouble for JOURNAL and PLAYBACK, so
  272. be careful when you are using multiple disks with journal.  (See FUTURES for
  273. additional comments on disk-requesters).
  274.  
  275. Since JOURNAL will be writing lots of data to its output file, and PLAYBACK
  276. will be reading losts of data from the journal file, the journal file must be
  277. on a disk that can remain in a drive.  RAM: is a good candidate for small
  278. journals, but may not have room for a large journal plus the programs that will
  279. be running.
  280.  
  281. JOURNAL's input handler allocates memory for the events as it copies them.  
  282. This memory is not freed again until JOURNAL actually records the event.  If
  283. events are coming in very fast, JOURNAL may not be able to keep up with them. 
  284. This may use up considerable memory until JOURNAL can catch up.  If you are
  285. having memory problems while using JOURNAL, try slowing down your mouse
  286. movements to give JOURNAL some time to catch up.
  287.  
  288. You may need to run JOURNAL and PLAYBACK at higher priorities than your normal
  289. processes in order to give them enough time to get the events to and from the
  290. input handler in a timely fashion.  Both progams use the Wait() function and
  291. neither "busy waits," so they should cooperate with other tasks even when they
  292. are at a higher priority.
  293.  
  294. If your journal runs a program that has to be loaded from disk, be sure to
  295. wait long enough for it to be loaded during the PLAYBACK.  Some disks take
  296. longer than others, and sometimes there are slight timing differences between
  297. JOURNAL and PLAYBACK.  Give a little extra time after disk accesses before you
  298. move the mouse or press a key.
  299.  
  300. JOURNAL only records mouse and keyboard events that come through the input
  301. device.  It does NOT record events that are received directly by a program
  302. through a message port from devices opened explicitly by the program.  For
  303. example, if your program opens the timer device and gets timer messages, these
  304. are NOT recorded by JOURNAL.  Similarly, JOURNAL does not record messages from
  305. the serial port, parallel port, or second mouse port.  Note that this means
  306. that JOURNAL will not record joystick motions from the second mouse port, so
  307. PLAYBACK can not reproduce them.  This may make it impossible to make a journal 
  308. record of some games.
  309.  
  310.  
  311. FUTURES:
  312.  
  313. The disk insert problem mentioned in USAGE NOTES above needs to be fixed.  The 
  314. only solution I can think of is to use SetFunction to replace AutoRequest with 
  315. a function that signals the JOURNAL or PLAYBACK process that a request has 
  316. occured, then calls the original AutoRequest, then signals when the request is 
  317. finished.  JOURNAL and PLAYBACK would "pause" until the AutoRequest was done,
  318. and then continue recording or playing back.  Since AutoRequest allows you to
  319. specify what kinds of flags will cancel the request, the replacement routine
  320. could check these to see if DISKINSERTED messages will satisfy it.  If not,
  321. then the original AutoRequest could be called without signalling the JOURNAL
  322. or PLAYBACK processes.  This way we would not be trapping the wrong requesters.
  323. Unfortunately, Workbench disk requests do not seem to use the DISKINSERTED
  324. flag, so something more sophsticated may be needed.  I am open to suggestions.
  325.  
  326. In the future (if there is enough interest), I plan to write a journal editor
  327. that allows you to step through a recorded journal and modify it by changing
  328. the events, adding new events, or deleting events.  Also, you will be able to
  329. add "special effects" like pop-up windows that contain explanations of what
  330. your program is doing, what qualifier keys are being pressed, etc.  I also
  331. hope to allow you to do this via the narrator device rather than through a
  332. window, if desired.  If I get real ambitious, I might even add something
  333. to play music from a file, but that will have to be far future for now.  If
  334. you want these features, please let me know.
  335.  
  336.  
  337. AUTHOR:
  338.  
  339. Davide P. Cervone
  340. University of Rochester Computing Center        DPVC@UORDBV.BITNET
  341. Taylor Hall                                     dpvc@tut.cc.rochester.EDU
  342. Rochester, New York  14627                      dpvc@ur-tut.UUCP
  343. (716) 275-2811
  344.